<HTML>
<HEAD>
<link rel="stylesheet" type="text/css" href="css.css">
<TITLE>Sanewall, Adding new services to sanewall.</TITLE>
<meta name="author" content="Costa Tsaousis">
<meta name="robots" content="noindex">
<meta name="description" content="

Home for sanewall, an iptables stateful packet filtering firewall builder for Linux (kernel 2.4),
supporting NAT, SNAT, DNAT, REDIRECT, MASQUERADE, DMZ, dual-homed, multi-homed and router setups,
protecting and securing hosts and LANs in all kinds of topologies. Configuration is done using
simple client and server statements while it can detect (and produce) its configuration
automatically. Sanewall is extremely easy to understand, configure and audit.

">

<meta name="keywords" content="iptables, netfilter, filter, firewall, stateful, port, secure, security, NAT, DMZ, DNAT, DSL, SNAT, redirect, router, rule, rules, automated, bash, block, builder, cable, complex, configuration, dual-homed, easy, easy configuration, example, fast, features, flexible, forward, free, gpl, helpme mode, human, intuitive, language, linux, masquerade, modem, multi-homed, open source, packet, panic mode, protect, script, service, system administration, wizard">
<meta http-equiv="Expires" content="Wed, 19 Mar 2003 00:00:01 GMT">
</HEAD>

<BODY bgcolor="#FFFFFF">

<p>

It is very simple to extend sanewall for simple single socket services.
There are two different ways to do it.<p>

<table border=0 cellpadding=10 cellspacing=0 width="100%">
<tr><td bgcolor="#EEEEEE"><b>The service definition syntax</td></tr></table>
<br>
The first needs a small service definition
somewhere at the beginning of the sanewall configuration file.
<p>
For example the following:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	server_myservice_ports=&quot;proto/sports&quot;
	client_myservice_ports=&quot;cports&quot;
</pre></b>
</td></tr>
</table>
</center>

Where:
<ul>
	<li><b>myservice</b> is the name of the service,<br>&nbsp;</li>
	<li><b>proto</b> is either <b>tcp</b>, <b>udp</b>, <b>icmp</b> - or whatever else iptables accepts
	as protocol, including numeric representations of protocols<br>&nbsp;</li>
	<li><b>sports</b> is the port number (or port name or port range) the server is listening at.
	To specify port ranges use the iptables syntax: i.e. 1000:1010 will match all ports from
	1000 to 1010 inclusive.<br>The special keyword <b>any</b> will match any server port.<br>&nbsp;</li>
	<li><b>cports</b> is the port (or port name or port range or space separated list of ports) clients might use to connect to the server.
	There are two keywords that can be used for <b>cports</b>:
	<br>&nbsp;
	<ul>
		<li><b>any</b> is a keyword that matches any client port.
		<br>&nbsp;
		</li>
		<li><b>default</b> is a keyword that matches the default client ports and it resolves to:
		<br>&nbsp;
		<ul>
			<li>if it is used for a localhost client (i.e. <a href="commands.html#client">client</a>
			within an <a href="commands.html#interface">interface</a>), it resolves to a list of ports as set
			by the Linux kernel and controlled by the <b>sysctl</b> variable <b>net.ipv4.ip_local_port_range</b>
			(or <b>/proc/sys/net/ipv4/ip_local_port_range</b>),
			<br>&nbsp;
			</li>
			<li>if it is used for a client running at remote host (i.e. <a href="commands.html#server">server</a>
			within an <a href="commands.html#interface">interface</a> or any kind within
			a <a href="commands.html#router">router</a>), it resolves to the contents of the sanewall variable
			<a href="commands.html#DEFAULT_CLIENT_PORTS">DEFAULT_CLIENT_PORTS</a>.
			<br>&nbsp;
			</li>
		</ul>
		</li>
	</ul>
</ul>
Just the above two lines will allow you to use (for example):

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	interface eth0 internet
		server myservice accept
		client myservice reject

	router myrouter
		route myservice drop
</pre></b>
</td></tr>
</table>
</center>
later in the configuration file.
<p>
As an example, assuming that the IMAP4 service was not defined in sanewall you would have to write:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	version 5

	server_imap_ports="tcp/143"
	client_imap_ports="default"

	interface eth0 lan0
		server imap accept

	interface eth1 lan1
		client imap reject

	router lan2lan inface eth0 outface eth1
		route imap accept
</pre></b>
</td></tr>
</table>
</center>
<p>
<table border=0 cellpadding=10 cellspacing=0 width="100%">
<tr><td bgcolor="#EEEEEE"><b>The inline service definition syntax</td></tr></table>
<br>
The second way is to use the <b>inline service definition syntax</b>:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
		server custom myservice proto/sports cports accept
</pre></b>
</td></tr>
</table>
</center>

All the parameters are the same with the one presented above, in the previous section.
<p>

The IMAP4 service example above, now becomes:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	version 5

	interface eth0 lan0
		server custom imap tcp/143 default accept

	interface eth1 lan1
		client custom imap tcp/143 default reject

	router lan2lan inface eth0 outface eth1
		route custom imap tcp/143 default accept
</pre></b>
</td></tr>
</table>
</center>

So, if you are only going to need a service just once in your firewall, it might be convenient to use
the inline syntax, while if you are going to need it many times, it would be easier to use the service
definition syntax.<br>
Personally, I always prefer to use the service definition syntax and to avoid the inline one (I always forget
that the inline one requires a service name too...).

<p>
<table border=0 cellpadding=10 cellspacing=0 width="100%">
<tr><td bgcolor="#EEEEEE"><b>Multi-socket, but simple servers</td></tr></table>
<br>
Both of the expressions, given above for defining more services, accept multiple arguments.
<p>
Fox example, assume there is a service named <b>serveme</b> that listens at two ports, port <b>1234 TCP</b> and <b>1234 UDP</b>.
The expected client ports are the default random ports a system may choose, plus the same port numbers the server is listening at.
<p>
To define this service you will have to write:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	version 5

	server_serveme_ports="tcp/1234 udp/1234"
	client_serveme_ports="default 1234"

	interface eth0 lan0
		server serveme accept

	interface eth1 lan1
		client serveme reject

	router lan2lan inface eth0 outface eth1
		route serveme accept
</pre></b>
</td></tr>
</table>
</center>
In this situation, sanewall simply produces all the combinations between client and server ports and generates
multiple iptables statements to accomplish them.
<p>
This is also the reason why the protocol cannot be defined in client ports.

<p>
<table border=0 cellpadding=10 cellspacing=0 width="100%">
<tr><td bgcolor="#EEEEEE"><b>Requiring kernel modules</td></tr></table>
<br>
Each service can be configured to require two sets of kernel modules depending whether <a href="commands.html#SANEWALL_NAT">NAT is enabled or not</a>.
This is done on a per service basis, so that if a service is not used in a configuration, sanewall will not load the module.
<p>
The general format is:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	require_service_modules="some_module"
	require_service_nat_modules="some_module_for_nat"
</pre></b>
</td></tr>
</table>
</center>

As an example you can see the complete IRC definition within sanewall:

<center><table border=0 cellpadding=15 cellspacing=20 width="70%">
<tr><td bgcolor="#F0F0F0">
<b><pre>
	server_irc_ports="tcp/ircd"
	client_irc_ports="default"

	require_irc_modules="ip_conntrack_irc"
	require_irc_nat_modules="ip_nat_irc"

	ALL_SHOULD_ALSO_RUN="${ALL_SHOULD_ALSO_RUN} irc"
</pre></b>
</td></tr>
</table>
</center>

The last statement in the above example says to sanewall, that if the configuration is using the <a href="services.html#all">all</a> service,
sanewall should indirectly also setup the <a href="services.html#irc">irc</a> service with all the <a href="commands.html#parameters">optional rule parameters</a>
of the <a href="services.html#all">all</a> service.

<p>
<table border=0 cellpadding=10 cellspacing=0 width="100%">
<tr><td bgcolor="#EEEEEE"><b>Complex services</td></tr></table>
<br>
Complex services are those that use multiple sockets initiated on both directions (where the client becomes a server and vice versa) of the communication,
and possibly involving protocols beyond TCP and UDP.
<p>
Currently you will have also to consider as complex all the services that you would prefer not to implement
using the connection tracker of iptables (i.e. stateless). In the future, and if there is enough demand, I might expand simple services to handle stateless
services too.
<p>
To write a complex service you will have to write a BASH function. It is not hard, but it is not two lines of code too, and most probably I am going to change
the interface to those functions in the future, as sanewall evolves. So, if you write one, please sumbit a patch so that I will be able to change your function
if and when I change the interface to those functions.
<p>
Note however that there are a few types of currently complex services that I'll try to avoid. These are all those services that in order to be implemented in
a stateful way there must exist a kernel module for them. If I support these services now, sanewall will loose its beauty since it will have to have ranges of
ports completely open to everyone just in case your service wants them.
There are plenty of <a href="http://www.netfilter.org/documentation/HOWTO//netfilter-extensions-HOWTO.html">such kernel modules</a> in an experimental state, which you can use if you decide to patch and recompile
your kernel. If you do this, I'll be glad to support your <b>stateful</b> rules about them. If you try to allow such services in a stateless maner by, for
example, allowing uncodintionally all traffic at high numbered ports... you are on your own.
<p>
If you decide to write a complex service, open sanewall in your favorite editor and find all the functions that start with <b>rules_</b>. All these functions define rules for
the complex services currently supported. If you know the basics of BASH programming, the existing functions will give you a clear idea of what you have to do to write your
own.

<p>
<table border=0 cellpadding=10 cellspacing=0 width="100%">
<tr><td bgcolor="#EEEEEE"><b><a name="distributed">Distribution of services with third party packages</a></td></tr></table>
<br>
Sanewall v1.213 and above includes a feature that allows third parties to install new service definitions
in the directory <b>/etc/sanewall/services</b>. The purpose of this feature is to allow the distributors of
third party packages (like proxy servers, dns servers, etc) automatically install their service definitions
in your system when their applications are installed.
<p>
To install a service definition, just create a file with any name, but with extension <b>.conf</b> in the
directory <b>/etc/sanewall/services</b>. The file itself must be a BASH script with any logic in it. The only
requirements are:
<ul>
	<li>The script sets up one or more service definitions, either in simple or complex form.</li>
	<li>The first line of the script looks like this:
	<p>
	<b>#FHVER: 1:213</b>
	<p>
	The two numbers are the major and minor versions of the sanewall service definition API. In fact,
	the major number (1) is increased if the API logic is changed, and the minor (213) is the minimum version of
	sanewall the service is expected to work with.
	<p>
	Sanewall will deny to run the service if the major number is different or if the installed version
	of sanewall is older than the one expected by the service.
	</li>
</ul>


<p>
<hr noshade size=1>
<table border=0 width="100%">
<tr><td align=center valign=middle>
	<A href="http://sourceforge.net"><IMG src="http://sourceforge.net/sflogo.php?group_id=58425&amp;type=5" width="210" height="62" border="0" alt="SourceForge Logo"></A>
</td><td align=center valign=middle>
	<b>Sanewall</b>, a firewall for humans...<br>
	&copy; Copyright 2004
	Costa Tsaousis <a href="mailto: costa@tsaousis.gr">&lt;costa@tsaousis.gr&gt</a>
</body>
</html>
